home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / tagsgen.exe / TAGS.DOC < prev    next >
Text File  |  1992-03-29  |  34KB  |  858 lines
  1.  
  2. ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
  3. ▒┌                                                                          ┐▒
  4. ▒                          Tags Generator V1.7                               ▒
  5. ▒                                                                            ▒
  6. ▒            A TAGS generator for Assembly and C and written in C            ▒
  7. ▒                   V1.7 Dedicated to the Public Domain                      ▒
  8. ▒                                                                            ▒
  9. ▒                             March 29, 1992                                 ▒
  10. ▒                              J. Kercheval                                  ▒
  11. ▒                      [72450,3702] -- johnk@wrq.com                         ▒
  12. ▒└                                                                          ┘▒
  13. ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
  14.  
  15. 03-30-92
  16.  
  17. This is V1.7
  18.  
  19. Fixed a number of C parsing bugs, including a problem with the C++
  20. extern "C" {...} statement and a number of small annoyances with
  21. preprocessor directives again.
  22.  
  23. Support was added for V6.0 of Epsilon for the new tag file format.  The
  24. previous format is available via the -o5 output switch.  In addition,
  25. the first line (the tag header) of the output tag file specified via the
  26. -t switch is dealt with correctly (while using the -oe switch).
  27.  
  28.                                     jbk
  29.  
  30. 11-12-91
  31.  
  32. This is V1.6
  33.  
  34. Added a junk filter for the C parser to eradicate unwanted tokens
  35. which were normally delimiters but were being tagged due to syntactic
  36. nuisances introduced through the twisted use of preprocessor
  37. directives and 'soft' syntax errors such as a ';' at the end of a
  38. procedure.  Added the -? switch as a common synonym for -h.
  39.  
  40.                                     jbk
  41.  
  42. 10/07/91
  43.  
  44. This is V1.5
  45.  
  46. The moment you post something, you (or normally, someone else) finds
  47. a bug to let you know what a peon you really are.  V1.4 had problems
  48. with extended enumeration constants and syntactic vagaries regarding
  49. enum declarations.
  50.  
  51.                                     jbk
  52.  
  53. 10/04/91
  54.  
  55. This is V1.4
  56.  
  57. A bug was fixed in assembly tagging (local labels using ':' were
  58. being tagged when defines were enabled regardless of -al flag).
  59. Exclude file parsing (-x flag) was added.  Support for tagging of
  60. enumeration constants and internal static declarations (-ck -ci) was
  61. added.  Improved support of LISTFILES, now the list file may be in
  62. the form of a response file and filenames may be separated by '+',
  63. ',', ';' or whitespace (comments delimited by '#' are still
  64. supported).
  65.  
  66.                                     jbk
  67.  
  68. 10/01/91
  69.  
  70. This is V1.3
  71.  
  72. A bug was fixed in cleanup code executed on Ctrl-C, Break, file
  73. error, or memory allocation error.  In V1.2, one of these errors
  74. normally resulted in some lost chains in the file structure but only
  75. manifested on a failure condition.
  76.  
  77.                                     jbk
  78.  
  79. 9/30/91
  80.  
  81. This is V1.2
  82.  
  83. This code is dedicated to the Public Domain, this means you may use
  84. this code for any purpose and for any reason and without any
  85. warranty, suitability to task, etc.  Public Domain also means that
  86. you may not place your own Copyright on this code.  Do not claim it
  87. to be your work.  Portions of this are under GNU CopyLeft (read the
  88. GNU.DOC file included in this distribution).  In particular the sort
  89. module (sort.c std.h) are under both GNU CopyLeft and individual
  90. Copyright.  If you need to be rid of CopyLeft to use this utility you
  91. will have to roll your own (or obtain another public domain) sort
  92. engine.
  93.  
  94. If you do use this and then make changes, bug fixes, or better still,
  95. add a new language parser (PASCAL, FORTRAN, BASIC come to mind right
  96. off the top) or create a macro for a particular editor to deal with
  97. tag files, then please route these changes to me and I will
  98. incorporate these changes and repost the package.
  99.  
  100. The intent of this utility and the release of its source to the
  101. Public Domain is in the interest of high quality programming and code
  102. generation.  Quality is designed in at the earliest stages and must
  103. be maintained by the use of high quality development and maintenance
  104. tools.  If professionals doing good work devote some talent and time
  105. to projects such as this and other projects then the programming
  106. community as a whole benefits (enough evangelism).
  107.  
  108.  
  109.                                     jbk
  110.  
  111. ------------------------------------------------------------------------------
  112.  
  113. Authors:
  114.  
  115.     J. Kercheval
  116.         johnk@wrq.com
  117.         [72450,3702]
  118.  
  119.         Overview and Architecture
  120.         C Module:
  121.         ASM Module:
  122.         Shell:
  123.         Arglist:
  124.         *IX wildcard:
  125.         Match:
  126.         Flags:
  127.         Tag IO (Format, styles and merge):
  128.         Modifications to Sort module to allow use as separate module
  129.             and some subtle bug fixes.  Context diff in SORTMISC.ZIP
  130.         Epsilon extensions:
  131.  
  132.     Mike Haertel
  133.         Free Software Foundation
  134.  
  135.         Original Sort Module:
  136.  
  137.  
  138.     Kevin Dean
  139.         Fairview Mall P.O. Box 55074
  140.         1800 Sheppard Avenue East
  141.         Willowdale, Ontario
  142.         CANADA    M2J 5B9
  143.  
  144.         CRC Validation Module:
  145.  
  146.  
  147. Contributors:
  148.  
  149.     Leonid Kokin
  150.         leok@wrq.com
  151.  
  152.         Brief macro:
  153.  
  154.  
  155. Thanks:
  156.  
  157.     Shane Hartman
  158.         ksh@ai.mit.edu
  159.     Eric Halpern
  160.         erich@wrq.com
  161.     Tad Marshall
  162.         tad@wrq.com
  163.  
  164.         Beta testing and usability editing for distribution
  165.  
  166. ------------------------------------------------------------------------------
  167.  
  168. Program Description:
  169.  
  170.     This utility implements a tags generator for assembly and C code.
  171. This module has been written for and is designed around the 80x86
  172. platform but is written with platform specific code as isolated as
  173. possible.
  174.  
  175.     Tags are informative lines stored (usually) within an ascii file
  176. and specify three things.  First a tag contains a token or an
  177. identifier which is a definition or declaration within the source
  178. code, second a tag contains the file name where that particular token
  179. is defined and third a typical tag will have an offset into the file
  180. where the token is defined (for example a character offset or a line
  181. number).  Occasionally a tag will be generated for an environment
  182. which likes the actual line which is the definition (GNU Emacs and
  183. Epsilon for example) specified instead of a file offset. This type of
  184. tag is sometimes used and is supported by this generator since, while
  185. it is possible for more than one line in a file to be the same and be
  186. VERY different in context, it has an advantage in that if your source
  187. module changes, the tag will probably still be found.
  188.  
  189.     The resulting tag file is intended to be used by an extensible
  190. editor or browser to traverse (possibly) widely placed code during
  191. planning, creation, maintenance and modification of medium and large
  192. projects.
  193.  
  194.     The tags file is used as an index into source definitions.  The
  195. typical implementation allows the user to place the cursor on the
  196. token to be found, start a macro (usually bound to a key) and have
  197. the editor place the cursor at the location which that token is
  198. defined.  This makes code traversal very simple.  If in addition, the
  199. macro implements a history, then moving around code becomes very
  200. similar to using a hypertext system.
  201.  
  202.     This generator has been designed to be used within a project make
  203. file and has a large number of options designed to make the task of
  204. generating and maintaining a tags file as simple and fast as
  205. possible.  There are three good methods for generating tags out of a
  206. makefile and each method is best for particular situations.  The
  207. examples below use OPUS make scripts as makefile code samples.
  208.  
  209.     1)  The first method is to generate a new tag file every time the
  210.         executable is generated.  This method is the simplest to
  211.         implement and is good for small and very small projects.
  212.  
  213.         This would be accomplished with either a list file or a macro
  214.         within the makefile.  Fo